<header>
    接口文档
</header>
<h2>
    配置画笔
</h2>
<h3>
    可配置项
</h3>
<pre tag="javascript">
painter.config({
    // 填充色或图案
    "fillStyle": 'black',

    // 轮廓色或图案
    "strokeStyle": 'black',

    // 线条宽度(单位px，下同)
    "lineWidth": 1,

    // 文字水平对齐方式（"left"左对齐、"center"居中和"right"右对齐）
    "textAlign": 'left',

    // 文字垂直对齐方式（"middle"垂直居中、"top"上对齐和"bottom"下对齐）
    "textBaseline": 'middle',

    // 设置线条虚线，应该是一个数组[number,...]
    "lineDash": [],

    // 阴影的模糊系数，默认0，也就是无阴影
    "shadowBlur": 0,

    // 阴影的颜色
    "shadowColor": "black",

    // 文字大小
    "fontSize": 16,

    // 字体
    "fontFamily": "sans-serif",

    // 字重
    "fontWeight": 400,

    // 字类型
    "fontStyle": "normal",

    // 圆弧开始端闭合方式（"butt"直线闭合、"round"圆帽闭合、"-round"反圆帽闭合）
    "arcStartCap": 'butt',

    // 圆弧结束端闭合方式，和上一个类似
    "arcEndCap": 'butt'
})
</pre>
<div class="version">
    丰富日志
    <hr />
    <ul>
        <li>
            arcStartCap的-round 0.3.0 新增
        </li>
    </ul>
</div>
<h3>
    渐变色
</h3>
<div class="version">
    0.3.0 新增
</div>
<p>
    上述配置颜色的地方，除了可以配置纯色外，还可以使用下面的渐变色。
</p>
<h4>
    线性渐变
</h4>
<p>
    使用画笔的createLinearGradient创建线性渐变对象，四个参数分别表示渐变的起点P(x1, y1)和终点P(x2, y2)：
</p>
<pre tag="javascript">
    let gradient = painter.createLinearGradient(x1, y1, x2, y2)
</pre>
<div class="warn">
    温馨提示：画笔上述参数的单位是px（下同）。
</div>
<h4>
    环形渐变
</h4>
<p>
    使用画笔的createRadialGradient创建环形渐变对象，三个参数分别表示渐变的圆心P(cx, cy)和半径r：
</p>
<pre tag="javascript">
    let gradient = painter.createRadialGradient(cx, cy, r1, r2)
</pre>
<div class="warn">
    温馨提示：渐变的起点是圆心。
</div>
<h4>
    设置与使用
</h4>
<p>
    设置渐变范围以后，你需要在渐变范围中添加渐变色，可以添加任意多个：
</p>
<pre tag="javascript">
    gradient.setColor(deep, color)
</pre>
<p>
    上述deep取值为闭区间[0, 1]，color可以是任意合法的颜色值。
</p>
<p>
    渐变如何使用，直接调用渐变的value方法即可：
</p>
<pre tag="javascript">
painter.config({
    "fillStyle": gradient.value()
})
</pre>
<p>
    如上面，我们给画笔设置填充色就是使用了我们刚刚获取的渐变色。
</p>
<h2>
    画笔方法
</h2>
<h3>
    文字
</h3>
<p>
    在点(x, y)处绘制填充的文字text；deg表示文字旋转角度，可选：
</p>
<pre tag="javascript">painter.fillText(text, x, y, deg)</pre>
<div class="warn">
    除非特别说明，角度全部采用弧度制。
</div>
<p>
    在点(x, y)处绘制轮廓的文字text；deg表示文字旋转角度，可选：
</p>
<pre tag="javascript">painter.strokeText(text, x, y, deg)</pre>
<p>
    在点(x, y)处绘制轮廓并填充的文字text；deg表示文字旋转角度，可选：
</p>
<pre tag="javascript">painter.fullText(text, x, y, deg)</pre>
<h3>
    多行文字
</h3>
<p>
    简单的理解就是设置了文本显示的宽以后，如果文本超过一行，会自动换行显示。
</p>
<div class="version">
    0.2.0 新增
</div>
<p>
    在点(x, y)处绘制填充的文字contents，且其宽不超过width；lineHeight表示行高，默认1.2，可选；deg表示文字旋转角度，可选：
</p>
<pre tag="javascript">painter.fillTexts(contents, x, y, width, lineHeight, deg)</pre>
<p>
    返回一个数字，表示实际文字所占的高。
</p>
<p>
    在点(x, y)处绘制轮廓的文字contents，且其宽不超过width；lineHeight表示行高，默认1.2，可选；deg表示文字旋转角度，可选：
</p>
<pre tag="javascript">painter.strokeTexts(contents, x, y, width, lineHeight, deg)</pre>
<p>
    返回一个数字，表示实际文字所占的高。
</p>
<p>
    在点(x, y)处绘制轮廓并填充的文字contents，且其宽不超过width；lineHeight表示行高，默认1.2，可选；deg表示文字旋转角度，可选：
</p>
<pre tag="javascript">painter.fullTexts(contents, x, y, width, lineHeight, deg)</pre>
<p>
    返回一个数字，表示实际文字所占的高。
</p>
<h3>
    计算文字宽
</h3>
<p>
    返回当前画笔状态下，文本的宽：
</p>
<pre tag="javascript">let width = painter.textWidth(text)</pre>
<h3>
    弧
</h3>
<p>
    以(cx, cy)为圆心，内外半径分别是r1和r2，从弧度beginDeg开始，跨越弧度deg，绘制填充圆弧：
</p>
<pre tag="javascript">painter.fillArc(cx, cy, r1, r2, beginDeg, deg)</pre>
<p>
    和fillArc方法类似，只不过绘制的是轮廓圆弧：
</p>
<pre tag="javascript">painter.strokeArc(cx, cy, r1, r2, beginDeg, deg)</pre>
<p>
    和fillArc方法类似，只不过绘制的是轮廓并填充圆弧：
</p>
<pre tag="javascript">painter.fullArc(cx, cy, r1, r2, beginDeg, deg)</pre>
<h3>
    圆形
</h3>
<p>
    以(cx, cy)为圆心，半径r绘制填充圆形：
</p>
<pre tag="javascript">painter.fillCircle(cx, cy, r)</pre>
<p>
    以(cx, cy)为圆心，半径r绘制轮廓圆形：
</p>
<pre tag="javascript">painter.strokeCircle(cx, cy, r)</pre>
<p>
    以(cx, cy)为圆心，半径r绘制轮廓并填充圆形：
</p>
<pre tag="javascript">painter.fullCircle(cx, cy, r)</pre>
<h3>
    矩形
</h3>
<p>
    以(x, y)为左上角，宽width，高height绘制填充矩形：
</p>
<pre tag="javascript">
    painter.fillRect(x, y, width, height);
</pre>
<p>
    以(x, y)为左上角，宽width，高height绘制轮廓矩形：
</p>
<pre tag="javascript">painter.strokeRect(x, y, width, height)</pre>
<p>
    以(x, y)为左上角，宽width，高height绘制轮廓并填充矩形：
</p>
<pre tag="javascript">painter.fullRect(x, y, width, height)</pre>
<h3>
    路径
</h3>
<p>
    基于路径可以绘制几乎大部分图形，非常类似画笔在纸上划动。
</p>
<h4>
    基础
</h4>
<p>
    开始一段独立的路径：
</p>
<pre tag="javascript">painter.beginPath()</pre>
<p>
    闭合当前路径，也就是路径首尾闭合：
</p>
<pre tag="javascript">painter.closePath()</pre>
<p>
    画笔移动到点(x, y)，此时笔离开了画布：
</p>
<pre tag="javascript">painter.moveTo(x, y)</pre>
<p>
    画笔移动到点(x, y)，此时笔没有离开画布：
</p>
<pre tag="javascript">painter.lineTo(x, y)</pre>
<p>
    以(cx, cy)为圆心，半径r，从弧度beginDeg开始，跨越弧度deg画弧，此时笔没有离开画布：
</p>
<pre tag="javascript">painter.arc(cx, cy, r, beginDeg, deg)</pre>
<p>
    把当前路径包裹的区域填充颜色：
</p>
<pre tag="javascript">painter.fill()</pre>
<p>
    把当前路径上色（轮廓线）：
</p>
<pre tag="javascript">painter.stroke()</pre>
<p>
    把当前路径画上轮廓线并填充颜色到当前路径所包裹的区域：
</p>
<pre tag="javascript">painter.full()</pre>
<h4>
    贝塞尔曲线
</h4>
<p>
    二次贝塞尔曲线到：
</p>
<pre tag="javascript">painter.quadraticCurveTo(cpx, cpy, x, y)</pre>
<div class="warn">
    只有一个控制点p(cpx, cpy),画笔当前的位置和p(x, y)分别是起点和终点。
</div>
<p>
    三次贝塞尔曲线到：
</p>
<pre tag="javascript">painter.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)</pre>
<div class="warn">
    有两个控制点p(cp1x, cp1y)和p(cp2x, cp2y),画笔当前的位置和p(x, y)分别是起点和终点。
</div>
<h4>
    记录
</h4>
<p>
    暂存当前路径：
</p>
<pre tag="javascript">painter.save()</pre>
<p>
    恢复上次暂存路径：
</p>
<pre tag="javascript">painter.restore()</pre>
<h4>
    裁剪
</h4>
<div class="version">
    0.3.0 新增
</div>
<p>
    生成裁剪区域，后续只能在裁剪区域中渲染：
</p>
<pre tag="javascript">painter.clip()</pre>
<h3>
    擦除画面
</h3>
<pre tag="javascript">painter.clearRect(x, y, w, h)</pre>
<h3>
    toDataURL
</h3>
<div class="version">
    0.2.0 新增
</div>
<pre tag="javascript">painter.toDataURL().then(url=>{
    // todo
})</pre>
<h3>
    getColor
</h3>
<div class="version">
    0.3.0 新增
</div>
<p>
    获取画布上指定位置的颜色：
</p>
<pre tag="javascript">
    var rgba = getColor(x, y)
</pre>
<h2>
    区域管理
</h2>
<p>
    有时候，我们可能需要和绘制的图表进行交互，比如点击的时候，需要知道点击的是哪个区域，就可以借助下面的方法：
</p>
<h3>
    设置区域
</h3>
<p>
    每次绘制一个区域前修改一下区域的名称，那么绘制的内容就会被记录起来：
</p>
<pre tag="javascript">
painter.setRegion(regionName)
</pre>
<h3>
    获取区域
</h3>
<p>
    比如点击了画布后，传递点击的位置，就可以返回当前位置所在区域的名称：
</p>
<pre tag="javascript">
painter.getRegion(x, y).then((regionName) => {
    // todo
})
</pre>
<h3>
    区域模式
</h3>
<p>
    是否绘制的内容只需要进行区域记录：
</p>
<pre tag="javascript">
painter.onlyRegion(flag)
</pre>
<p>
    如果flag为true，那么或许所有的操作都不会同步到画布中，只会被区域记录，重新设置成false即可退出区域模式。
</p>
<h2>
    原生画笔
</h2>
<div class="version">
    0.2.0 新增
</div>
<p>
    也就是canvas上的原生画笔，没有经过任何修饰的：
</p>
<pre tag="javascript">
let ctx = painter.getContext(isRegion = false)
</pre>
<p>
    可以传递一个参数isRegion，默认false表示返回的是画布的，如果设置true返回的就是区域的。
</p>
<h3>
    如何配合区域控制？
</h3>
<p>
    如果你使用此处的原生画笔绘制，默认是无法自动与区域管理机制配合运行的，不过，你可以手动使其一致。
</p>
<p>
    比如你用下面的方法获取了画布的原生画笔并绘制了一个矩形：
</p>
<pre tag="javascript">
let ctx = painter.getContext()
ctx.fillRect(0, 0, 100, 50)
</pre>
<p>
    那么，你如果给画布添加了点击事件，并使用setRegion设置区域名称，然后在点击的时候通过getRegion来获取是否点击在这个矩形上的。
</p>
<p>
    非常不幸，你会发现机制失灵了。
</p>
<p>
    怎么办？非常简单，只需要再加一段代码：
</p>
<pre tag="javascript">
let ctxRegion = painter.getContext(true)
ctxRegion.fillRect(0, 0, 100, 50)
</pre>
<p>
    下面是完整的例子代码：
</p>
<example tag="api/oral-canvas" height="200px"></example>
<div class="warn">
    温馨提示：ctxRegion永远都不应该修改fillStyle、strokeStyle、shadowColor等色彩相关的属性。
</div>